Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update capabilities.md #102

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Update capabilities.md #102

wants to merge 2 commits into from

Conversation

craigc01
Copy link

Added a lost parenthesis and added clarity on the << symbol.

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
Added a lost parenthesis and added clarity on the << symbol.

Signed-off-by: Craig Christianson <[email protected]>
@@ -96,9 +96,9 @@ By convention the 0th CSlot is kept empty, for the same reasons as keeping NULL
process virtual address spaces: to avoid errors when uninitialised slots are used unintentionally.

The field `info->CNodeSizeBits` gives a measure of the size of the initial
CNode: it will have `1 << CNodeSizeBits` CSlots. A CSlot has
CNode: it will have `1 << CNodeSizeBits` CSlots where the `<<` symbol represents the left bit shift operator. A CSlot has
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we could drop the shift and say instead:

Suggested change
CNode: it will have `1 << CNodeSizeBits` CSlots where the `<<` symbol represents the left bit shift operator. A CSlot has
CNode: it will have `2 ^ CNodeSizeBits` CSlots

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the 2^N notation is more clear, but there are a lot of places in the tutorials where the 1u << N notation is used that should probably be changed for consistency. It also may be used in code examples, but so far it looks like the code examples favor the BIT( ) macro. I think it is safe to assume that the reader is familiar with C notation. The only reason I added it was to ensure that the symbol is not confused with the "much less than" meaning of the << symbol. I think either way would work, and I don't really have a preference. I just think the notation should be consistent. What are your thoughts?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the context of that sentence << as "much less than" doesn't really make sense, so while there can be initial confusion, it should clear up eventually. I do agree that it'd be nicer not to cause any initial confusion either, though.

Overall 2^n either with super script or with ^ does seem nicer to me, at least for mathematically minded people. I think the 1 << _ notation is used to be consistent with the code. Since it's a tutorial and is trying not to introduce everything at once, the BIT macro is not used there yet and I don't think it's the place to introduce it.

If we want do 2^n instead of 1 << _ in the text, we should really review all of the tutorials an stay consistent. We should also check if that leads to strangeness in other parts of the tutorials (probably fine, though).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(of course ^ is the xor operator, so I'm sure 2^n will also be confusing to someone out there)

@axel-h
Copy link
Member

axel-h commented Jul 13, 2023

My understanding is that the BIT() should be used in the code. For docs, I consider using 2^n a bit nicer. Or something that renders to superscript, which some renderers seem to do for "^", but it is not standard.

@craigc01
Copy link
Author

Sounds good. I'll take another look at it. I'll convert this to draft for now.

@craigc01 craigc01 marked this pull request as draft July 13, 2023 23:59

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
Changed 1>>N notation to 2^N notation
@craigc01 craigc01 marked this pull request as ready for review July 18, 2023 16:37
@craigc01
Copy link
Author

Here is what it looks like with the superscript. Initially, it seemed less readable to me, so I added some text for clarity.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants